
/*
 * Copyright 2002-2012 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2012原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.xml;

import org.w3c.dom.Element;
import org.w3c.dom.Node;

import org.springframework.beans.factory.config.BeanDefinition;
import org.springframework.beans.factory.config.BeanDefinitionHolder;
import org.springframework.lang.Nullable;

/**
 * Base interface used by the {@link DefaultBeanDefinitionDocumentReader}
 * for handling custom namespaces in a Spring XML configuration file.
 *
 * <p>Implementations are expected to return implementations of the
 * {@link BeanDefinitionParser} interface for custom top-level tags and
 * implementations of the {@link BeanDefinitionDecorator} interface for
 * custom nested tags.
 *
 * <p>The parser will call {@link #parse} when it encounters a custom tag
 * directly under the {@code <beans>} tags and {@link #decorate} when
 * it encounters a custom tag directly under a {@code <bean>} tag.
 *
 * <p>Developers writing their own custom element extensions typically will
 * not implement this interface directly, but rather make use of the provided
 * {@link NamespaceHandlerSupport} class.
 *
 * @author Rob Harrop
 * @author Erik Wiersma
 * @since 2.0
 * @see DefaultBeanDefinitionDocumentReader
 * @see NamespaceHandlerResolver
 */
/**
 *｛@link DefaultBeanDefinitionDocumentReader｝使用的基本接口
 *用于处理Spring XML配置文件中的自定义命名空间。
 *
 *＜p＞实现将返回
 *｛@link BeanDefinitionParser｝接口用于自定义顶级标记和
 *｛@link BeanDefinitionDecorator｝接口的实现
 *自定义嵌套标记。
 *
 *＜p＞解析器在遇到自定义标记时将调用｛@link#parse｝
 *当
 *它直接在｛@code＜bean＞｝标记下遇到一个自定义标记。
 *
 *＜p＞开发人员编写自己的自定义元素扩展通常会
 *不直接实现此接口，而是使用提供的
 *｛@link NamespaceHandlerSupport｝类。
 *
 *@作者Rob Harrop
 *@作者Erik Wiersma
 *@自2.0起
 *@参见DefaultBeanDefinitionDocumentReader
 *@参见NamespaceHandlerResolver
 */
public interface NamespaceHandler {

	/**
	 * Invoked by the {@link DefaultBeanDefinitionDocumentReader} after
	 * construction but before any custom elements are parsed.
	 * @see NamespaceHandlerSupport#registerBeanDefinitionParser(String, BeanDefinitionParser)
	 */
	/**
	 *之后由｛@link DefaultBeanDefinitionDocumentReader｝调用
	 *构造，但在解析任何自定义元素之前。
	 *@see NamespaceHandlerSupport#registerBeanDefinitionParser（字符串，BeanDefinitionParse）
	 */
	void init();

	/**
	 * Parse the specified {@link Element} and register any resulting
	 * {@link BeanDefinition BeanDefinitions} with the
	 * {@link org.springframework.beans.factory.support.BeanDefinitionRegistry}
	 * that is embedded in the supplied {@link ParserContext}.
	 * <p>Implementations should return the primary {@code BeanDefinition}
	 * that results from the parse phase if they wish to be used nested
	 * inside (for example) a {@code <property>} tag.
	 * <p>Implementations may return {@code null} if they will
	 * <strong>not</strong> be used in a nested scenario.
	 * @param element the element that is to be parsed into one or more {@code BeanDefinitions}
	 * @param parserContext the object encapsulating the current state of the parsing process
	 * @return the primary {@code BeanDefinition} (can be {@code null} as explained above)
	 */
	/**
	 *分析指定的｛@link Element｝并注册任何结果
	 *｛@link BeanDefinition BeanDefinitions｝与
	 *｛@link org.springframework.beans.factory.support.BeanDefinitionRegistry｝
	 *它嵌入在提供的｛@link ParserContext｝中。
	 *＜p＞实现应返回主｛@code BeanDefinition｝
	 *如果希望嵌套使用，则从解析阶段得到
	 *例如，在｛@code＜property＞｝标记内。
	 *＜p＞如果需要，实现可能返回｛@code null｝
	 *<strong>不能在嵌套场景中使用</strong>。
	 *@param元素要解析为一个或多个｛@code BeanDefinitions｝的元素
	 *@param parserContext封装解析过程当前状态的对象
	 *@return主｛@code BeanDefinition｝（可以是｛@ccode null｝，如上所述）
	 */
	@Nullable
	BeanDefinition parse(Element element, ParserContext parserContext);

	/**
	 * Parse the specified {@link Node} and decorate the supplied
	 * {@link BeanDefinitionHolder}, returning the decorated definition.
	 * <p>The {@link Node} may be either an {@link org.w3c.dom.Attr} or an
	 * {@link Element}, depending on whether a custom attribute or element
	 * is being parsed.
	 * <p>Implementations may choose to return a completely new definition,
	 * which will replace the original definition in the resulting
	 * {@link org.springframework.beans.factory.BeanFactory}.
	 * <p>The supplied {@link ParserContext} can be used to register any
	 * additional beans needed to support the main definition.
	 * @param source the source element or attribute that is to be parsed
	 * @param definition the current bean definition
	 * @param parserContext the object encapsulating the current state of the parsing process
	 * @return the decorated definition (to be registered in the BeanFactory),
	 * or simply the original bean definition if no decoration is required.
	 * A {@code null} value is strictly speaking invalid, but will be leniently
	 * treated like the case where the original bean definition gets returned.
	 */
	/**
	 *解析指定的｛@link Node｝并修饰提供的
	 *｛@link BeanDefinitionHolder｝，返回修饰的定义。
	 *＜p＞｛@link Node｝可以是｛@linkorg.w3c.dom.Attr｝或
	 *｛@link Element｝，取决于自定义属性或元素
	 *正在分析。
	 *＜p＞实现可以选择返回一个全新的定义，
	 *这将替换结果中的原始定义
	 *{@link.org.springframework.beans.factory.BeanFactory}。
	 *＜p＞提供的｛@link ParserContext｝可用于注册任何
	 *需要额外的bean来支持主定义。
	 *@param source要分析的源元素或属性
	 *@param definition当前bean定义
	 *@param parserContext封装解析过程当前状态的对象
	 *@return修饰的定义（要在BeanFactory中注册），
	 *或者如果不需要修饰，则只使用原始bean定义。
	 *｛@code null｝值严格来说是无效的，但会很宽松
	 *与返回原始bean定义的情况类似。
	 */
	@Nullable
	BeanDefinitionHolder decorate(Node source, BeanDefinitionHolder definition, ParserContext parserContext);

}
